<div id="preamble">

  <h3>Architecture Suggestions</h3>

<p>
In this section, LB = load balancer (the module + apache).
<br>* VERY IMPORTANT NOTE *
<br>The shared memory segment, locks, and mod_athena engine are shared by ALL virtual hosts in
a particular configuration. It exists per httpd instance. 
If you run more than one instance, be sure to have unique
shm and mutex paths for each.
</p>
<p>
The following are layout building blocks, and can function by themselves, or in 
combination. The frist three combine easily with that last two. Any setup can be mirrored,
and you can use a http reverse proxy setup as a standalone at the same time.
</p>

<ul id=toc>
<li> (1) <a href="#inproxy">LB in main proxy server instance</a></li>
<li> (2) <a href="#behind">LB between proxy and content/app servers</a></li>
<li> (3) <a href="#standalone">LB standalone</a></li>
<li> (4) <a href="#mirror">LB mirroring setup</a></li>
</ul>
<br>
<ul>
<li> <a name="inproxy"><b>(1) LB in main proxy server instance</b></a>
<p>
This is the simplest, fastest and most likely setup for most installations. A request
looks like this:<br>
<code>client: --- :proxy+mod_athena: --- :application server</code>
<br>where ":" represents network interfaces.
</p>
<p>
There is one installation of httpd with the athena module on the machine running the 
proxy+mod_athena. The configuration allows for incoming client requests 
(http or https) on the outside facing interface, but forbids by Location rule 
access to the load balancer engine (see <a href="mod_athena_directives.html#AthPath">AthPath</a>).
The server also listens on an internal interface, http only, that allows access to the
engine for the application servers to send their statistics updates (along with the 
proxied traffic). You could separate update traffic from proxied requests 
if you wanted by running another interface on the proxy and each appserver on another network.
</p>
<p>
Each incoming, non-engine request will be passed through mod_proxy that you have configured
mod_proxy to handle. If it is handled by mod_proxy, then mod_athena will also inspect it
after mod_proxy has done the url rewrite. If the rewritten hostname matches a farm, it will
then rewrite the request again and hand it back to mod_proxy for completion.
</p>
<p>
This model lends itself to an easy <a href="#mirror">mirroring</a> setup.
</p>
</li>

<li> <a name="behind"><b>(2) LB between proxy and content/app servers</b></a>
<p>
If for some reason, eg. security prejudice or design, or platform limitations, 
you wanted to completely separate out the load balancing stage, then you would 
have a setup just like above, but the client would be your other proxy server.
You would configure that proxy server to pass all requests you want to be load 
balanced to the server running httpd+mod_athena.
<br><code>client: --- :proxy: ---...
<br>&nbsp; &nbsp; ...--- (:)proxy+mod_athena: --- :application server</code>
<br>in this case (:) is an optional interface.
</p>
<p>
This model adds some overhead, since you have to tear apart the request one extra time, but
has advantages for portability and flexibility.
</p>
</li>

<li> <a name="standalone"><b>(3) LB standalone</b></a>
<p>
For installations where there is no reverse proxy setup, you can always use mod_athena
as a standalone load balancer. Very simply, you have your servers send updates,
either standard OS level stats or additional stats you insert programmatically, and then 
you query the loadbalancer from your program with an http(s) request to its "/balance" 
feature.
</p>
<p>
An example where this is desireable is a system that handles both synchronous web requests,
but also runs background tasks. Imagine a java servlet that handles report configuration, but
also background execution in a stateless environment (state in back-end database).
The synchronous requests would be handled as in model (1), but
but the servlet has some asynchronous method to queue and run the background threads.
It would query the load balancer to signal the process to run on the least busy server.
</p>
</li>

<li> <a name="mirror"><b>(4) LB mirroring set up</b></a>
<p>
An included script provides an easy way to mirror from one mod_athena instance
to another. Everything is done through http. The target server should be configured
with the identical layout of farms and physicals, and have mirroring enabled.
</p>

<p>
One easy way to do this have the primary and secondary (only if they are on
separate machines) share the same httpd.conf over NFS.
</p> 
</ul>

</div>

